home *** CD-ROM | disk | FTP | other *** search
/ Languguage OS 2 / Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO / language / suif / readme next >
Text File  |  1994-10-24  |  16KB  |  393 lines
  1. This is the README file for the Stanford SUIF compiler system.
  2.  
  3. Please read this file in its entirety before building the SUIF system.
  4.  
  5.  
  6. TABLE OF CONTENTS:
  7.  
  8.     Copyright notice
  9.     WHAT SUIF IS / WHAT SUIF IS NOT
  10.     OTHER SOFTWARE THAT YOU WILL NEED
  11.     CONTENTS OF THE DISTRIBUTION
  12.     INSTALLATION INSTRUCTIONS
  13.     USING THE SUIF SYSTEM
  14.     OLD SUIF VS. NEW SUIF
  15.     SUIF SUPPORT / MAILING LISTS
  16.     GETTING STARTED WITH SUIF
  17.  
  18. **********************************************************************
  19.  
  20. This software is Copyright (c) 1994 Stanford University.
  21.  
  22.     All rights reserved.
  23.  
  24.     Permission is given to use, copy, and modify this software for any
  25.     non-commercial purpose as long as this copyright notice is not
  26.     removed.  All other uses, including redistribution in whole or in
  27.     part, are forbidden without prior written permission.
  28.  
  29.     This software is provided with absolutely no warranty and no
  30.     support.
  31.  
  32. **********************************************************************
  33.  
  34. WHAT SUIF IS
  35.  
  36. SUIF is a collection of programs and libraries, mostly written in C++,
  37. that allow researchers to investigate issues in scalar and parallel
  38. optimization.  The SUIF distribution contains all the pieces necessary
  39. for a working compiler that will translate C or FORTRAN into either a
  40. MIPS (R3000) executable or back into C code (suitable for compiling
  41. with a native compiler).  It contains passes to do a variety of
  42. transformations including parallel loop detection, parallel code
  43. generation, cache-based loop transformations, and scalar
  44. optimizations.  The SUIF system will correctly compile most major
  45. benchmark suites.  SUIF also provides a set of core libraries that (we
  46. hope) allow people to easily write new SUIF passes to investigate
  47. their favorite compiler research topic.
  48.  
  49.  
  50. WHAT SUIF IS NOT
  51.  
  52. SUIF is not a production compiler.  It is not suitable for replacing
  53. your native compiler.  Don't even attempt to compile a kernel with it.
  54. SUIF does not have many code generators.  SUIF will not generate
  55. scalar code that's as good as your native compiler (unless you use the
  56. "C" backend and actually compile with your native compiler...)  If you
  57. are running a machine that is not MIPS-based, you will have to use the
  58. "C" backend and feed the result into your native C compiler (SUIF will
  59. do this automatically).  SUIF is not supported software.  It is
  60. distributed without warranty.  We will do what we can to help you with
  61. problems, but in the end you're on your own.  See the end of this file
  62. for information on mailing lists about SUIF.
  63.  
  64. **********************************************************************
  65.  
  66. OTHER SOFTWARE THAT YOU WILL NEED
  67.  
  68. The SUIF system uses a lot of software from the GNU project.  Although
  69. you may be able to adapt it to work with other compilers, you'll save
  70. yourself a lot of trouble by using the programs specified below.
  71. These programs are available by anonymous ftp from one of the GNU ftp
  72. servers, such as prep.ai.mit.edu or gatekeeper.dec.com.  Note that
  73. most of these packages have been compressed with the gzip program; you
  74. will have to compile and install gzip before you can uncompress the
  75. others.  This is explained in greater detail in the README files on
  76. the ftp servers.  The version numbers below reflect the versions that
  77. we are currently using.
  78.  
  79.         gzip                            1.2.4
  80.  
  81.         bison                           1.22
  82.         gcc/g++                         2.5.8
  83.         libg++                          2.5.3
  84.         gmake                           3.70
  85.  
  86. Also the GNU debugger will be helpful if you design your own SUIF
  87. applications:
  88.  
  89.         gdb                             4.12
  90.  
  91. **********************************************************************
  92.  
  93. CONTENTS OF THE DISTRIBUTION
  94.  
  95. This rest of this file describes the structure of the distribution,
  96. and tells how to compile and install the software.
  97.  
  98. The "ReleaseNotes" file describes information specific to the current
  99. release.
  100.  
  101. The "WhatsNew" file describes differences between SUIF releases.
  102.  
  103. The "FAQ" file includes answers to commonly asked questions.
  104.  
  105. The "src" directory contains the sources for all SUIF software.
  106.  
  107. The "man" directory contains man pages for SUIF programs.
  108.  
  109. The "docs" directory contains PostScript versions of the SUIF
  110. documentation.
  111.  
  112. The "info" directory contains GNU Emacs info versions of the SUIF
  113. documentation.
  114.  
  115. The "html" directory contains HTML (for the World Wide Web) versions
  116. of the SUIF documentation.
  117.  
  118. The "src/examples" directory contains examples of simple SUIF passes
  119. and sample input files.  These files are taken from various manuals.
  120.  
  121. **********************************************************************
  122.  
  123. INSTALLATION INSTRUCTIONS
  124.  
  125. The SUIF system is fairly machine-independent.  So far we have
  126. compiled it successfully on MIPS-based DEC and SGI machines, Sun SPARC
  127. machines running SunOS, and on x86 machines running Linux.  See the
  128. ReleaseNotes for current information on the status of SUIF under these
  129. and other systems.
  130.  
  131. Depending on your platform, define the MACHINE environment variable as
  132. follows:
  133.  
  134.     MIPS-based DEC systems:             MIPSEL
  135.     MIPS-based SGI systems:             SGI
  136.     Sun SPARC systems running SunOS:    SPARC
  137.     Linux systems:                      LINUX
  138.     Any other host:                     The processor type of the host
  139.                                             (like "RS6000" or "CRAY3")
  140.  
  141. SUIF will be installed in the hierarchy in which it is compiled.  If
  142. you want it installed elsewhere, you will have to copy the binaries
  143. there after compilation is complete.
  144.  
  145. Define the SUIFHOME environment variable to the top-level directory of the
  146. SUIF hierarchy.  (This is the directory containing this README file).
  147. Now add $SUIFHOME/$MACHINE/bin to your path.  It is essential that your
  148. path contain this directory when you begin installation because the
  149. installation needs to use scripts it will find there.
  150.  
  151. You will need about 96 MB of disk space to compile and install SUIF.
  152. The compilation of the entire system lasts about four hours on a
  153. DECstation 5000.
  154.  
  155. ---
  156.  
  157. PostScript, GNU emacs "info", and HTML versions of the SUIF manuals
  158. are included in the SUIF distribution.  You may wish to regenerate
  159. these manuals from the original source.  In this case you can do the
  160. following:
  161.  
  162. If you have the GNU emacs "info" package installed, you can set the
  163. environment variable BUILD_INFO, and new info files will be generated
  164. during installation.
  165.  
  166. If you have the TeX software (including dvips) and "texinfo.tex"
  167. support file installed, you can set the environment variable BUILD_PS,
  168. and new PostScript manuals will be generated during installation.
  169.  
  170. If you have the "texi2html" and "RosettaMan" converters installed, you
  171. can set the environment variable BUILD_HTML, and new HTML versions of
  172. the manuals will be generated during installation.
  173.  
  174. It does not matter what value you set these environment variables to,
  175. only that they are set.
  176.  
  177. ---
  178.  
  179. To build and install:
  180.  
  181. * Set the MACHINE variable.
  182. * Set the SUIFHOME variable.
  183. * Add $SUIFHOME/$MACHINE/bin to your path.
  184. * Change to the $SUIFHOME directory.
  185.  
  186. You may want to edit the Makefile to modify the list of targets to
  187. install.  For example, if you're using a SPARC platform there's no
  188. point in installing the MIPS code generator (mexp and mgen).
  189.  
  190. * Run "gmake setup"
  191. * Run "gmake install"
  192.  
  193. The "install" target will do a relatively quiet build/installation.
  194. Any errors that are encountered will be left in log files in the
  195. appropriate source directories.  If you would prefer to watch the
  196. build/install interactively, you can use the "install-noisy" target
  197. instead.
  198.  
  199. **********************************************************************
  200.  
  201. USING THE SUIF SYSTEM
  202.  
  203. Once you have installed the system, there is one more environment
  204. variable that must be set in order to have a working compiler.  This
  205. is the SUIFPATH variable that determines which directories will be
  206. searched for compiler binaries.  Like other PATH variables, its value
  207. is a list of colon-separated directory names which are searched in
  208. order from left to right.  Unless you have copied SUIF binaries to
  209. another location, the first thing on the list should be
  210. $SUIFHOME/$MACHINE/bin.
  211.  
  212. You will also want to add other directories to your SUIFPATH so that
  213. scc, the driver that calls the various passes, can use passes that are
  214. installed on your system but not distributed as part of SUIF.  The
  215. most critical of these is cpp, the ANSI C pre-processor.  This is
  216. _not_ provided with SUIF, so it's up to you to make sure you have this
  217. included in your path.  Many systems will have a cpp in /usr/lib.
  218. Note, however, that some systems use older pre-ANSI versions of cpp,
  219. so care must be taken.  If you don't have a system ANSI cpp, or if
  220. you're not sure it's ANSI, it is recommended that you use the version
  221. that comes with gcc.
  222.  
  223. Hint: the command "gcc -v" will show you which directory your
  224. installed version of gcc is using for its internal passes.  We've
  225. found that if you cd to $(SUIFHOME)/$(MACHINE)/bin and then run the
  226. csh command:
  227.  
  228.     ln -s `gcc -v |& head -1 | cut -d' ' -f4 | sed -e 's/specs/cpp/'`
  229.  
  230. a symlink will automatically be created to the cpp of the latest
  231. installed gcc.  Remember to repeat this after installing a new gcc.
  232.  
  233. As another example of the use of the SUIFPATH variable, if you plan to
  234. use the SUIF-to-C converter followed by some other C compiler as a
  235. portable back-end, you will want the directory containing that
  236. compiler in your SUIFPATH.
  237.  
  238. At this point you should make sure that all the environment variables
  239. you've set for SUIF are going to be set automatically whenever you use
  240. SUIF.  Typically that means putting them in your .login or .profile.
  241. The environment variables you should consider setting automatically
  242. are SUIFHOME, SUIFPATH, MACHINE, BUILD_INFO, BUILD_PS, BUILD_HTML, and
  243. your path.
  244.  
  245. Now you're ready to start running the SUIF passes.  You should start
  246. with scc, the driver that calls the other passes.  See the scc man
  247. page for details.
  248.  
  249. When you start to develop your own passes and link in the SUIF
  250. libraries, you will have to be careful about linking in the libraries
  251. that depend upon one another and the order in which they are
  252. specified; libraries cannot be linked in after other libraries that
  253. they use or the linker may already have discarded the needed symbols.
  254.  
  255. These are the current dependences among the SUIF libraries (note that
  256. general, hawg, flow, math, deptest, and sharlit are not listed as they
  257. are part of the obsolete old SUIF system and should not be used in new
  258. programs):
  259.  
  260.                           SUIF
  261.                           /|\ \
  262.                          / | \ \---------------\
  263.                     /---/  |  \                 \
  264.                    /       |   \-----\           \
  265.                   /        |          \           \
  266.                CHECK     USEFUL     NSHARLIT     SIMPLE
  267.                            |
  268.                         BUILDER
  269.                            |
  270.                         SUIFMATH
  271.                            |
  272.                        DEPENDENCE
  273.                            |
  274.                        TRANSFORM
  275.  
  276. This means, for example, that libbuilder depends on both libuseful and
  277. libsuif.  So a program using the builder library should include a
  278. line
  279.  
  280.     LIBS = -lbuilder -luseful -lsuif
  281.  
  282. in its Makefile.
  283.  
  284. The various libraries also have initialization functions that must be
  285. called.  Since they depend on one another, these initializations must
  286. be done in the correct order.  Fortunately, the standard Makefiles
  287. will handle all of this automatically if you call start_suif() before
  288. using any of the libraries.
  289.  
  290. **********************************************************************
  291.  
  292. OLD SUIF VS. NEW SUIF
  293.  
  294. Within the past year, much of the SUIF system has been rewritten from
  295. scratch.  The original SUIF system (now called "old SUIF") is
  296. obsolete, and the new SUIF system ("new SUIF", or just "SUIF") has
  297. taken its place.  Unfortunately, there are some parts of the old SUIF
  298. system that were not converted due to lack of time or motivation.
  299. These include the scalar optimizer ("oynk") and the MIPS code
  300. generator ("mexp" and "mgen").  To support these old SUIF passes, the
  301. old SUIF libraries are included in the distribution.  These libraries
  302. (deptest, flow, general, hawg, looptrans, math, and sharlit) are for
  303. backwards compatibility only and should never be used in newly written
  304. SUIF passes.  They are completely incompatible with the new SUIF
  305. libraries (builder, check, dependence, nsharlit, simple, suif,
  306. suifmath, transform, and useful).
  307.  
  308. So that old SUIF programs may be used, two conversion programs are
  309. provided.  oldsuif converts a new SUIF file to an old SUIF file.
  310. newsuif converts an old SUIF file to a new SUIF file.  Because the
  311. representation of the two file formats is different, these conversion
  312. programs may not be successful at preserving all information in a file
  313. when old SUIF passes are run between conversion.  For example, some
  314. annotations may be lost.
  315.  
  316. We hope at some point to completely eliminate old SUIF.  Anyone
  317. wishing to help us with this (such as by writing a new code generator)
  318. is quite welcome to do so.
  319.  
  320. **********************************************************************
  321.  
  322. SUIF SUPPORT / MAILING LISTS
  323.  
  324. The SUIF compiler system is released without warranty or promise of
  325. support.  Essentially you are on your own.  However, there are a
  326. number of mailing lists devoted to SUIF that you may join.  We
  327. recommend that you join at least the suif-announce mailing list, as
  328. notices of patch releases or new versions will be sent to this list.
  329.  
  330. suif-talk@suif.stanford.edu is for the discussion of anything related
  331. to SUIF.  It is for the use of SUIF users to talk amongst themselves.
  332.  
  333. suif-bugs@suif.stanford.edu is for the submission of bugs to the SUIF
  334. development team.  There is no guarantee that submitting a bug will
  335. cause that bug to be fixed.  Users may add themselves to the suif-bugs
  336. list if they wish to monitor other users' bug reports.
  337.  
  338. suif-announce@suif.stanford.edu is for the announcement of new
  339. versions of SUIF.
  340.  
  341. To join any of these lists, send mail to "majordomo@suif.stanford.edu"
  342. with the body:
  343.  
  344. subscribe list-name
  345.  
  346. Sending a message with the body:
  347.  
  348. help
  349.  
  350. will send info on other commands you may use.
  351.  
  352.  
  353. The SUIF team also maintains a World Wide Web server that includes
  354. information about SUIF, hypertext versions of the SUIF documentation,
  355. and published papers written by members of the SUIF team.  If you have
  356. access to a Web browser, such as NCSA Mosaic, you can use the URL:
  357.  
  358. http://suif.stanford.edu
  359.  
  360. **********************************************************************
  361.  
  362. GETTING STARTED WITH SUIF
  363.  
  364. The paper "The SUIF Compiler System" is an introduction to SUIF, its
  365. purpose, and its limitations.  It is available in the directory
  366. "docs/suif-overview.ps".
  367.  
  368. The man page for "scc" is the next thing to read.  "scc" is the driver
  369. that calls other SUIF passes.  It may be used just like "cc" or "f77"
  370. to generate an executable from a source, although some of the command
  371. line options may be different from your native compiler.  Man pages
  372. are also available for all SUIF programs.
  373.  
  374. If you are interested in using SUIF's parallelizing capabilities, you
  375. should read the SUIF Parallelizing Compiler Guide in
  376. "docs/parguide.ps".
  377.  
  378. If you are interested in developing SUIF passes, you should read the
  379. documentation for the SUIF library, "docs/suif.ps", and the SUIF
  380. Cookbook, "docs/cookbook.ps".  The latter contains a variety of
  381. examples of simple SUIF programs.  The source for these examples may
  382. also be found in the "src/examples" directory.
  383.  
  384. Finally, if you are developing complex applications, you may also be
  385. interested in the documentation for the SUIFMATH library
  386. (docs/suifmath.ps), BUILDER library (docs/builder.ps), TRANSFORM
  387. library (docs/transform.ps), DEPENDENCE library (docs/dependence.ps),
  388. and the Linear Inequality Calculator (docs/lic.ps).
  389.  
  390. **********************************************************************
  391.  
  392.             The Stanford Compiler Group
  393.